Copyright: © 1994 ViewPoint Technologies, Inc.
Citation: © 1994 ViewPoint Technologies, Inc.


Contents

Please click on the menu command, the area of the screen, or the topic on which you would like to see help.

The following additional Help Topics are available:

Overview of SourceWorks

Getting Started

Get And Put

Comparing And Merging Revisions

Conflicts: When Two People Change A File

Branching

Creating Releases

How To Get Support

Index of Topics


Why SourceWorks?

SourceWorks/VB is unique among version control systems.  SourceWorks is the only version control system specifically designed for group development with Visual Basic.  There are five key design principles behind SourceWorks.

•	Security.  SourceWorks maintains a central project database  for the team.  This database tracks every version of every file contributed by every developer.  SourceWorks never overwrites an existing version.  SourceWorks lets you immediately see what work you have done locally (updated working files) and what work other people have done (updated project files) since you last synchronized your work with the database.

•	Optimistic concurrency.  SourceWorks allows all of the team to have read/write access to the entire project, because it enforces consistency and synchronizes code automatically when team members check files in to the group repository.  SourceWorks immediately reports discrepancies between versions of a file and flags the differences, routine by routine.

•	Distributed responsibility.  SourceWorks assumes that every developer is best the person to merge his/her own work into the team project and does not rely on a separate person to act as a build manager.  SourceWorks offers every team member intelligent differencing and merging, sensitive to the file organization of VB, that lets any developer reconcile two versions of the same file.

•	Unobtrusiveness.  SourceWorks expects you to work with all the VB menu commands as you normally would.

•	Completeness.  SourceWorks manages all necessary files in the project, not just those in the MAK file.

SourceWorks will benefit every developer on the team.  Because SourceWorks allows team members to work in parallel, it will let the team perform as more than the sum of its parts.


Demonstration Version

This demonstration version is identical to the full SourceWorks Beta II release, with one modification:

You may only save ten (10) revisions of any file.

Obviously, the regular SourceWorks release lets you save an unlimited number of revisions.  And it contains several enhancements.  So, when you have finished trying out this demo and would like to use SourceWorks for real, call ViewPoint and order the commercial release: (508)655-9595.


Getting Started

If youre using VB now, you will be able to start using SourceWorks within an hour.  Use this chapter to familiarize yourself with SourceWorks concepts before you begin.  It covers three topics:

1.	Planning Your Directories

You will need to plan the organization of a few directories.  Consult this section for an example.

2.	Starting a SourceWorks Project

Use this section to create a SourceWorks database from an existing VB project or to create a new repository independent of VB.

3.	The Recommended Process

This is a little recipe for a sequence to use in working with SourceWorks and VB.  After the first couple tries, it will be second nature.  There are also some useful tips, especially for developers working in active teams.


The Recommended Process

Use VB for all of your coding, testing, and form design, and from VB save your project in your workspace.  SourceWorks will scan this directory for new versions and ensure consistent tracking of file revisions in the project database.  When you save your work, follow these steps.  (You can, of course, use the toolbar equivalents of the menu commands.)

Save your work frequently in VB.  On satisfactory completion and testing:

1. (In VB:) Save your project.

2. (In SourceWorks:)

This list shows all the files that other team members have put into the project database since you last refreshed your Workspace.  If you see any surprises, then compare file versions.

3.
If you see any surprises, compare file versions.

4.	(or Menu->Project->Synchronize)
This copies all of your work into the project database and moves all of the Updated Project Files (that you saw in step 2) into your workspace.  If you have locked any files, they will not be updated.

5.  (In VB:) Reload your project, retest and continue


Good Practice Guidelines

These are some practical guidelines for using VB and SourceWorks.

•	In VB, use the environment setting to Save As Text for all files.  (This does not affect existing files, so you should also resave them as text if necessary.)  Saving files as text will allow you to see version differences.

•	Lock files, when you are planning to do major changes.  This informs other users that you are making changes to these files and prevents them from putting modifications into the database.

•	Fill in working comments as you get files.  These will be picked up as the revision comments when you put files back.

•	Regularly check View->Updated Project Files menu to see which file revisions others have put into the project database.


Directory and Database Structure
Planning Your Directories

This is a SourceWorks directory structure for the mythical project MYAPP.  Each machine is indicated by a separate color; the network server is shown as S:.  (Accordingly, security is based on the network setup.)  Click on the directory which you would like to see defined.


Project Database (on the Server)

SourceWorks stores all versions of files in a central Microsoft Access database, which resides in the Project Directory.  Whenever a team member uses the File->Put command, the database is updated, making all file revisions and history immediately accessible to all developers in your team.

SourceWorks stores all versions of files in a central database, with the file extension .SDB, which resides in the Project Directory.  The database is in a format compatible with Microsoft Access.

This acts as a repository, storing every version of every file contributed by every developer.  Whenever a team member uses the File->Put command, the database is updated, making all file revisions and history immediately accessible to all developers in your team.

When you create a SourceWorks project you will be asked to choose the directory for the project database.


Reference Directory (on the Server)

This directory contains a complete set of current project files, read only, shadowing the most current versions of all files in the Project Database.  The Reference Directory is optional, and will be created based your choices in Project Properties.  Think of it as an insurance policy.

The Reference Directory is optional, and will be created based your choices under the Options dialog when you create a new project.  This directory contains a complete set of current project files, read only, shadowing the most current versions of all files in the project database.  This directory can be treated as a convenient place to find all the current project files in their DOS-readable formats.  Think of this directory as an insurance copy of the project, should your database ever be corrupted.


Release Directories (on the Server)

These directories are static.  Every time you create a project release in SourceWorks, you have the option to name and make a Release Directory, which will contain all of the files comprising that release.

These directories are static.  Every time you create a project release in SourceWorks, you have the option to name and make a Release Directory, which will contain all of the files comprising that release.


Local Working Directory (on Each Developers Machine)
Local Workspaces (on Each Developers Machine)

Each Workspace consists of:

1.	the Working Directory (named by the user when creating the workspace, for example C:\SRC\CURRENT in the above diagram), in which you edit and test the files in VB,

2.	the Backup Directory (named by default C:\SRC\CURRENT\BACKUP in this example), into which SourceWorks moves files before updating them in the Working Directory, and

3.	the File Attribute that SourceWorks sets on all files in the working directory (read/write or read-only).

The Default Workspace contains the project files that you actively edit, test, enhance, and run with VB.  Think of this as your sandbox, with your current copies of all project files.  Whenever you save files in this directory by using a VB Save Project, SourceWorks will automatically detect which existing project files have changed and what files have been added to the MAK file.

When you open a project in SourceWorks for the first time, SourceWorks will add you as a user to the project database.  SourceWorks will ask you to designate your Default Workspace and its Backup Directory at that time.  You may change these directories with the ProjectPropertiesUser dialog at any time subsequently.

•	In VB, always open the MAK file from your appropriate workspace.

•	Use the View->Updated Workspace Files command to see the table of files that have been changed by VB.  Select the ones that you want to copy into the Project Database and use the Put command to move them.

•	Use the Project->Update Workspace command to refresh this directory with new files from other team members.


Local Backup Directory (on Each Developers Machine)

This directory is for some of those times you want to say Oops (or something worse).  Your Backup Directory contains copies of files that you saved in your Working Directory and then overwrote in either of two ways:

•	You got a different version of the file from the project database.  SourceWorks will automatically scan for conflicts and prompt you before overwriting any files.  If you allow SourceWorks to overwrite, then it will move the version to be overwritten into the Backup Directory first.

•	You merged two versions of the file (see the Conflicts Chapter) and chose to write the merged result into your local working directory.  SourceWorks automatically moves the previous local copy to the Backup Directory.

This directory keeps only the most recent previous version of each file.  Versions that are in the project database are not duplicated in this directory.

This directory is for some of those times you want to say Oops (or something worse).  Your Backup Directory contains copies of files that you saved in your current workspace and then overwrote in either of two ways:

•	You got a different version of the file from the project database.  SourceWorks will automatically scan for conflicts and prompt you before overwriting any files.  If you allow SourceWorks to overwrite, then it will move the version to be overwritten into the Backup Directory first.

•	You merged two versions of the file and chose to write the merged result into your workspace.  SourceWorks automatically moves the previous local copy to the Backup Directory.

This directory keeps only the most recent previous version of each file.  Versions that are in the project database are not duplicated in this directory.


Security

SourceWorks relies on the security provisions of your network and does not rely on a separate scheme of its own.  Accordingly, SourceWorks assumes that a user who has permission to access the project database directory is authorized to see its contents.  If you want to limit the project to a certain list of users, use the network administration utilities to restrict access permission on the project directory to that list.


Creating A New SourceWorks Project

You can create a SourceWorks project in either of two ways:

1.	By loading an existing VB project into a SourceWorks project.  This is the case in which you have begun to work in VB and have source code that you wish to retain and track in SourceWorks.  SourceWorks will use the current project MAK file as its starting point for the database.

2.	By creating a new SourceWorks project without a VB MAK file.  This process is appropriate when a) you have not yet begun a project in VB, or b) intend to track files independent of a VB MAK file.  For example, you may want to create a SourceWorks repository to track files that are common to several VB projects, such as DLLs, VBXs, MDBs, ICOs, or global declarations.

Each process is described below.  In either case, you may add additional files into the SourceWorks database at any time and have SourceWorks track their subsequent revisions.


Loading an Existing VB Project Into SourceWorks

You can load an existing VB project into SourceWorks in a matter of minutes.  Here are the steps.

1.	Start with a known good version of source in VB.
(That may seem obvious, but it is still a good idea.)  SourceWorks will read your MAK file and look for its referenced FRM, FRX and BAS files in the same directory.  Therefore, be sure to save your MAK file in the same directory as the other source files.

2.	Save all FRM and BAS files as text ( in the Save As dialog).  Then exit VB or close the project.

3.	Launch SourceWorks.

4.	Select Project->New

This will prompt you for choices of the project to import and the directory for the project database.  By default, the project database will have the same name as the imported make file, and will be given the extension SDB.

4a.	(Optional:) If you wish to change the settings for the project properties, press Options.

Use this dialog to:

•	Deselect Require Revision Comments (to capture working comments every time files are put) and the automatic creation of reference copies of files.

•	Sort files internally when they are put (to use externally differencing programs).

•	Turn off file compression (necessary only if you are running NT on your workstation).

•	Designate the reference directory for copies of the current file revisions.

5.	Now designate your Workspace.  This is the directory which SourceWorks will into which put files and from which it will get files.  This should typically be on C: or another drive to which you always have guaranteed access.

5a.	(Optional:) If you wish to change your user settings for the project properties, press Options.  This allows you to forego using a backup directory.

6.	Enter revision comments, or accept the default, unless you have deselected this project option.

You will see a thermometer indicate the progress of loading files.

7.	Now in VB: Project->Open->Select the MAK file in your local Workspace.  It is essential to choose the right directory, as that is the directory where SourceWorks will read and write files.


Creating A New Project Without a MAK File

You may want to use a project that does not mirror a VB MAK file, for example, to store library modules, forms, DLLs, and database templates.  The process for creating a project without a MAK file is similar.  Merely deselect the checkbox under Import.


File Menu

This menu contains the commands that work on the files currently selected in the File View.  You can access the commands either by right mouse click or from the main menu.


File: Add

Use the File->Add command to copy into the Project Database those files that are not referenced by the projects MAK File.  These are typically DLL, HLP, ICO, BMP, TXT, MDB, or other types that VB does not edit directly. You can add anything whose version you would like to track.

You do not need to add:

•	Files referenced in the MAK file.  When you put the MAK file into the Project Database, SourceWorks adds these for you automatically.

•	FRX files.  SourceWorks automatically detects whether an FRM file has an accompanying FRX and adds the FRX with it.

SourceWorks will take care of these files automatically.


File: Get

Use Get to copy specific file revisions from the Project Database into your current Workspace.  By default, getting files will lock them.

To get the current revisions of all files (without locking), use the ProjectUpdate Workspace command.


File: Put

Use Put to copy file revisions from your current Workspace into the Project Database.  For more information, see the Get and Put section.


File: Unlock

Unlock removes the lock that you placed on the selected files.


File: Lock

Lock sets a lock on the selected files, without getting them.  If, for example, you realize that you have modified unlocked files due to a Search and Replace in VB, then you can lock them without affecting the copies in your workspace.


File: Viewer

This command shows you the contents of the chosen file revision.  View works on text, graphics, sound and multimedia files.


File: Rename

This lets you rename a file currently in the Project Database.


File: Remove

This lets you remove a file from the Project Database.  Only do this if you really want to lose history tracking for that file.  (Note that when you remove a FRM or BAS file from a projects MAK file, SourceWorks will automatically change the FRM or BAS files status property to Inactive, but will retain the file in the database.)


File: Compare/Merge

This command lets you compare and combine the contents of two revisions of the same text file.  For details, see Comparing and Merging.


File: Properties

Properties sets the properties tracked for each file, notably the status (active or inactive).  Do not confuse these file properties with the project properties.


File: History

History brings up the History View for the selected files.


Project Menu

These commands apply to the entire project.  Click on a command to see its definition.


Project: New

This command creates a new Project Database with the file extension .SDB.  When you create the project, you will be asked to specify the directories for the Project Database and your own Workspace.  At creation, you may designate an existing VB project (designated by a MAK file) to import.


Project: Open
Project: Open and Close

Open and Close do what youd expect on existing projects.  You can only have one project open at a time.


Project: Recent Project List

The Recent Project List at the bottom of the menu gives you a shortcut for opening commonly used projects.


Project: Update Project

Update Project is equivalent to a Put of all updated workspace files.  This makes all of your updated work available to team members in the Project Database.


Project Menu: Properties

Properties brings up the dialog for project properties (not the same as the file properties).


Project: History

History loads history for all the files.


Project: Synchronize

Synchronize is equivalent to a put of all Updated Workspace Files and get of all Updated Project Files.  Unfortunately, it is not working in this beta.


Project: Update Workspace

Update Workspace is equivalent to a Get of all updated project files.  This brings everyone elses work into your Local Working Directory.


Project: Lock

This command locks the entire Project Database.  The primary use of Project->Lock is to prevent other users from putting new file revisions while you are making a new project release.  Only the user who has locked the project may unlock it.


Project: Create Release

Create Release makes a new project release.  This will tag the appropriate file revisions, create a release directory, and record the release history.


Project: Release History

Release History displays the view of releases that have been previously created and lets you recreate a previous release.


Project: Compact and Repair Database

Compact Database and Repair Database are maintenance functions to clean up the Project Database.  These are the same as their equivalents in Microsoft Access.


View Menu

Use this menu to choose which subset of the currently active project files you would like to see in the File View.

	Click on the command you would like to see defined.


View Combo Box

Select the subset of the currently active project files you would like to see in the File View.  This is identical to making the choice from the View Menu.


Active Files

All current files in the project.  This will include anything in the VB MAK file, plus any additional files that you have added.


Inactive Files

Files in the project that are not currently used, either because you removed them from the make file or set the individual files status property to inactive.


Updated Workspace Files

Files that you have changed since you got them or last used the Project->Update Workspace command.


Updated Project Files

Files that someone else has changed since you got them or last used the Project->Update Workspace command.


Refresh
Refresh (F5)

Use this command to update the current view since the last refresh.  You can have them automatically refreshed by setting Project Properties, but you still need this command to see changes since the last refresh interval.


Set File Details

Use this command to choose the columns to display in the current view.


Options Menu

Use this menu to control Preferences and to turn the display of the toolbar and statusbar on or off.
Preferences has two tabs.  Use the General Preferences to:

•	Log in to the project database as a different user.

•	Change the Auto-Refresh setting, which controls the frequency with which the current File View is automatically updated.

•	Change the file view displayed when you start SourceWorks.

When you have Auto-Refresh on, you may notice a slight delay in other applications, while SourceWorks is updating the current view.

Use the Font Preferences to change the fonts used in the file and compare/merge viewers:


File View

This is the main view of SourceWorks.  Depending on your choice in the View Menu, it shows you one of four file groups: all active files, all inactive files, updated project files (due to someone elses changes), or updated workspace files (due to your own changes).  The status bar shows you which selection you made.  Click on a column to learn more about that field.

To change the display:

•	Use the View Menu to choose which files appear as rows.  To change the default view on startup, use Options->Preferences.

•	Use the View->File Details command to choose the columns to display in the current view.

•	Move the mouse pointer over the column titles to resize the columns. When you resize the columns, SourceWorks will remember your settings.


File View: Resizing

Move the mouse pointer over the column titles to resize the columns. When the mouse pointer changes shape, ClickLeft and Drag.


File View: Commands

Use the View Menu to change this display.


File Type

This icon indicates the type of file.  Note that you can store any file you want, not just the files that VB accepts in its MAK file.


File Name

These are DOS file names.  That is why SourceWorks gives you the other columns.  Double-click in this column to get or put the file.


Locked By

Name of the user who has the file locked, if any.  When you get or put a file you can set the lock.


Working Revision Number

This column shows the number of the revision that you last got from the Project Database into your current Workspace.  If there is an asterisk (*) next to it, then you have modified the file in your Workspace.


Project Revision Number

This column shows the number of the revision that is currently in the Project Database.  Normally, this is the same as the Working Revision Number to its left.  If it is greater than the Working Revision Number, then this number indicates that someone else has put a more current revision into the Database, which you should consider getting.


Description

This is the overall description for the file, one of the files properties. Double-click in this column or use File Properties to change it.


File Search

To search for a file by name start typing the beginning of the name.


File Details

Use the View->File Details command to bring up this dialog and change the choice of columns to display.


File Revision History

SourceWorks tracks history automatically for every file.  When a user puts the file into the Project Database, SourceWorks creates a history record.  You can look at history by selecting files and using the file menu (for example, from right click).

The comments you see here are the Working Revision Comments  that were captured when the various users put their file back into the Project Database. Of course, it is good practice to write meaningful comments.

Note that the History View shows all revisions that were put into the database, not just those that were used in creating releases.  There is a separate view for release history.


Release History

Whenever you create a release, SourceWorks creates a history record for that release.  Use Project->Release History to bring up this view.

The comments you see here are the Release Comments that were entered when each release was made.


Working Revision Comment

Double-click on this field to see or edit the full comment for this particular revision of the file.  By default, this will be suggested as the revision comment when you put the file back into the Project Database.


Locking Files

	You can lock or unlock a file at any time from the Toolbar or File menu.  Lock files, when you are planning to do major changes.
Locking:

1.	informs other users that you are making changes to these files,

2.	prevents other users from putting modifications to those files into the database, and

3.	prevents the Project->Update Workspace command from overwriting your work in progress.

When you get a file, it is locked for you by default.  You may retain or release the lock when you put it back into the database, depending on your setting of the check box of the put dialog.

Lock files when you are planning to do major changes, but not necessarily before every little edit.  Because VB makes it hard to anticipate accurately which files contain similar code, you often do not know which files you will need in advance.  SourceWorks will automatically scan for conflicts when a file is put into the Project Database or gotten from it.


Toolbar

These icons access the most frequently used commands: Open Project, Close Project, Update Workspace, Synchronize, Add File, Get, Put, View, and Compare.  If you let the mouse pointer linger over an icon, you will see a tool tip that provides the command name.  .


Statusbar

This shows you (from left to right):

•	the status of the last completed command,

•	the current Workspace,

•	the currently selected view you see (Active, Inactive, Updated Workspace Files, or Updated Project Files), and

•	the state of modifier keys.


Currently Selected View

This shows you the currently selected view you see (Active, Inactive, Updated Workspace Files, or Updated Project Files).


Modifier Keys

This shows you the state of Caps Lock, Insert and Num Lock.


Get and Put

	These verbs work on the files selected in the File View.
•	Use Get to bring files from the Project Database into your Working Directory.  SourceWorks will track the version that you get, so that it can later detect whether you have made changes.  To get all updated files, use Project->Update Workspace.

•	Use Put to move your updated work from your Working Directory back into the Project Database.

Both of these operations are completely safedont worry.  SourceWorks always warns you if it detects a file version conflict and lets you take corrective action.

Version Tracking

When you put a file into the Project Database, SourceWorks automatically assigns a new version number.  If SourceWorks detects a conflict, it will warn you and allow you either to merge the differences immediately or to create a new branch.

Putting the MAK File

When you put the MAK file into the Project Database, SourceWorks scans it to see if you have added any files in VB.  If you have, SourceWorks will add these files to the project.


Conflicts: When Two People Change The Same File

With VB, it often happens that two people change the same file.  SourceWorks is uniquely well suited to handling this situation.

SourceWorks never lets you overwrite the changes.  Whenever you get or put a file, SourceWorks checks to see whether there may be a conflict and warns you.

•	On Get, SourceWorks checks your Workspace to see whether any file has been changed and warns you before replacing it.  If you choose to overwrite the file, SourceWorks will move a copy into your Backup Directory.

•	On Put, SourceWorks checks the Project Database to see if anyone else has made changes.  If SourceWorks detects a conflict, it will allow you to merge the two versions before making the put.  In certain cases, you may want to put back a second variant of changes, in which case SourceWorks allows you to create a branch.

•	When the conflict arises, SourceWorks will display the following warning:

Choose Compare/Merge  (the default) to enter the sequencing for comparing and merging files.


Comparing and Merging

SourceWorks lets you view and merge differences between any two versions of a file.  You can always invoke this process with  the File->Compare/Merge command.  Additionally, when SourceWorks detects file conflicts, it can automatically suggest this process in its warning.

There are four steps:

1.	Choose the file versions.   These are referred to as A and B.  By default, A is the Local Working copy; B is the latest Project Database copy.

2.	View which routines have changed between the two versions.

3.	Reconcile the differences for each routine by selecting the A version or the B version, or by merging the two into a combined version.

4.	Save the merged file.


Differences: Viewing the Different Routines in the File

After you select two file versions, you will see this dialog.

	(Click on an area for more information.)


Differences: Merging Each Routine

After you choose to merge two variants of a routine, you see this form with the A and B variants of that routine only.  The differences are highlighted on either side, with counters indicating the number of lines that vary.

Click on any button or screen area for further information.


Merging: Edit Windows

You may edit the variants on either side, or cut and paste (Ctrl-C, Ctrl-V) between the windows.  Note that you will have to choose only one variant (A or B) when you are done, so it is smart to edit only on that side.


Merging: First Line

Press First Line to scroll vertically to the top of the currently selected variant (A or B).


Merging: Last Line

Press First Line to scroll vertically to the bottom of the currently selected variant (A or B).


Merging: Next Diff

Press Next Diff to scroll vertically to the next different line in the currently selected variant (A or B).


Merging: Next Equal

Press Next Equal to scroll vertically to the next line in the currently selected variant (A or B) which has a direct match in the other variant.


Merging: Use A or Use B

When you have finished editing, choose the variant (A or B) that you want to keep.  When you press Use A or Use B, SourceWorks will move the routine to the lower window of the differences form, so that it can be written into the merged output file.


Merging: Rescan

Use Rescan in two cases:

1.	To scan the entire windows again from the top, after you have edited one of the versions (A or B), and wish to see how many lines remain different.

2.	To scan down from the current cursor positions only, to see how many lines further down in the file remain different.  This is useful when lines have been inserted and you want to check the rest of the routine.  To use this option, be sure to position the text cursor in each window at the start of a line that is the same.  Differences above the cursors initial positions will be ignored.

After you press this button, choose whether to start scanning form the top or the current positions.


Merging: Cancel

Press Cancel to return to the previous screen and discard your edits.


Merging: Synch Scrolling

Use Synch Scrolling to make the two windows scroll in unison, both horizontally and vertically.  To scroll one window independently, deselect Synch Scrolling.


Merging: Line Counters

These counters show you (for each of the A and B versions, how many lines of the total are different.  These counters are refreshed when you press the Rescan button.


Merging: Routine Name

This is the particular routine you chose on the previous screen.


Choosing Which Versions to Compare

This dialog lets you specify which versions of the file to compare.  By default, SourceWorks will choose your current local copy and the most recent version in the Project Database, but you can select any two versions.  Note which is A and which B, as these will be used for differences.

When you are done, the results will be written to your current Workspace.  If you overwrite the copy in your workspace directory, the version prior to the merge will be moved to your workspace backup directory.


Compare/Merge Dialog: Upper Window

The upper window shows you the routines whose differences are unresolved.  The status column indicates whether the routine appears in both file versions, in A only, or in B only.


Compare/Merge Dialog: Upper Buttons
Compare/Merge Dialog: Use A or Use B

The buttons let you choose the action to take.  Press one of these use the A or B version of the routine as is.


Compare/Merge Dialog: Compare

Double-click on the routine name or press Compare to view and merge the two variants.


Compare/Merge Dialog: Cancel

Cancel this dialog to return to the file view.


Compare/Merge Dialog: Lower Window

The lower window shows you the routines that will be written to the file on saving.  The status column indicates whether the routine was the same in both files, whether you chose to use the A or the B variant, or whether you created a new merged routine.


Compare/Merge Dialog: View

The View button invokes the standard file viewer to show you any routine.


Compare/Merge Dialog: Revert

Revert throws away the edits that you have made and moves the routine back to the upper window.


Compare/Merge Dialog: Saving

The Save button writes out a file into your current Workspace with the routines from the lower window only.  If you leave any routines in the upper window, they will be discarded.  The history button produces the Revision History, just like the File->History command.


Recovering Historical Files
Recovering Historical File Revisions

SourceWorks lets you recover historical version of files in two ways:

•	You can retrieve any historical version of a file that was put into the Project Database from the History View  with the Get command.

•	If you overwrote a file in your Local Working Directory, you can also recover that from your Local Backup Directory.  You can use either SourceWorks or VBs  File->Add command or use the Windows File Manager to recover it.


Branching

Branches are parallel revisions to the same parent version of a file. Branches allow you to track the delivery of different release versions of a project to different customers or bug fixes made in historical releases.  SourceWorks tracks File Versions in a hierarchy to allow consistent tracking of File History, like this:

Creating Branches

Branch numbering is created for you automatically, when you put a version of a file back into the database and request a branch or when SourceWorks detects a conflict.  To force a branch, set the corresponding option when putting the file into the database:


Creating Releases

SourceWorks lets you create discrete releases (sometimes referred to as milestones) for your project.  Creating a release updates the history table so that you can track which file versions belonged to which release versions.  It also (optionally) lets you create a Release Directory with copies of all the files in that release.

The steps to create a release are simple:

1.	Project->Lock.  This prevents anyone else from putting files, until you unlock the project.

2.	Project->Create Release.  At this stage you choose which versions of the files comprise the release, enter the release name, description, and release directory.

By default, the release will use the current revisions of all active files in the project database.  You may change this in two ways:

•	Change the settings under Options to use the file revisions that are currently in one of your workspaces.   For example, if you have recreated a historical release and fixed bugs, this allows you to quickly generate the bug fix release.

•	Use Revisions to select explicit revisions of the files.

3.	(Optional)  Use Revisions to select alternate file versions if necessary.  You will see this table, which shows you the revision number comment for each file that will go in the release.

To change a revision for a file, highlight the file and press Browse.  This will display that files history and allow you to select a different revision.  Note that you can toggle between viewing the table of all file revisions (By Revision) and just those revisions that were used in previous releases (By Release).

4.	Project->Unlock.  Now everyone can put files back again.


Naming Releases

SourceWorks tracks release names when you create releases.  These are not the same as file version numbers, which are automatically created when you get and put files from/to the project database.  Release Names should be meaningful names that you will use for tracking and reporting.  They will be used are view revisions by release, as on the File History view.


Working with Alternate Releases

SourceWorks allows you to maintain separate Workspaces in order to work on different releases in parallel.  For example, you may want to recreate a historical release to fix bugs, or you may want to maintain parallel releases for different product configurations.

Use Project->Properties->User->Workspace to create a new workspace or to select an existing one.  You will see the currently available workspaces.

To create a new workspace, press Add.  You may then choose which file revisions to copy into the new workspace.

•	Choose Current revisions, for example, if you want to work on a second configuration with the current file revisions or if you want to split a large project.  This is the default.

•	Choose a specific Release if you want to recreate the historical release, for example, to fix reported bugs.

Under Workspace, specify the name and location for the workspace.


Recreating Historical Releases

If you want to recreate a historical release, without creating a new Workspace for tracking the files:

1.	Select Project->Release History and highlight the release you require.

2.	Select Recreate.  You will see this dialog.

3.	Specify the target directory for the files and press OK.


Project Properties

There are two tabs for setting Project Properties: General (for all users) and User (for the current user only):

General (for all users). The most important general properties are the switch to Require Revision Comments (when files are put into the project database) , the choice of Compression, and the location for the Reference Directory.  Compression will shrink the database size by 65-75% and speed up the refresh time for the views.  Unfortunately, however, compression is not compatible with the use of NT on your local workstation (although it poses no problem if you use NT for the file server).  Deselect compression only if you plan to use NT on any developers workstation.
User (for the current user workspace only).  These properties control the workspaces directory locations and file attributes (read/write or read/only).  Press Workspace to change the selected workspace or to create a new one.


Installation

Setup

To install SourceWorks, you must be running Microsoft Windows-> 3.10 or 3.11.  Insert disk 1 in drive A: and, from the file manager, double click a:setup.exe.  Then follow the prompts.  (If appropriate, substitute drives or directories.)  The SourceWorks program files will take up to three megabytes of disk, although they may take much less if you already have certain DLLs and VBXs installed.

Troubleshooting Installation

SourceWorks does not overwrite newer versions of any VBX or DLL files.  In certain cases, you may see a message warning you of incompatible DLLs or VBXs.  This may happen because SourceWorks left another programs existing DLL unchanged, because another program overwrote a file after you installed SourceWorks, or because you changed you path statement after installation.

To review which files SourceWorks expects and what changes it actually made to your system, review the file, INSTALL.LOG, in the SourceWorks program directory.  This file recorded all changes that were made to your system during installation.


Workspace
Alternate Workspace

It is often important to separate the bug fixing, maintenance, and testing of a historical release from your current revisions.  SourceWorks allows you to have multiples workspaces for a project, so that you can work on multiple releases simultaneously.  When you recreate a historical release, SourceWorks will prompt you for the choice of the alternate workspace to use.  For bug fixing, maintenance, and testing, it is often necessary to recreate a historical release in a separate workspace.

When you are using multiple workspaces, be sure in VB always to open the MAK file from your appropriate workspace.


Current Workspace

The name of your currently selected workspace is shown here on the status bar.


File Version Numbers

SourceWorks automatically creates file version numbers.  Any time you get or put files, the versions are checked for consistency.


Release Names

SourceWorks tracks release names when you create releases.  These are not the same as file version numbers, which are automatically created, when you get and put files from/to the Project Database.


Saving from VB

Be sure to save your VB files as text.


Support

ViewPoint Technologies offers a free support forum on CompuServe.  To enter it, type GO VIEWPOINT.  There is also a free membership offer for CompuServe enclosed with this product.  Please post your questions to our forum leader at ID 74774,2154.

Within a year of your purchase of SourceWorks, you are entitled to free telephone support for 90 days starting with the date of your first call.  If you would like a premier support contract with ViewPoint, please call and ask about support contract options.


Help

Click here to see this help system.


Branches

Branches are parallel revisions to the same parent version of a file. Branches allow you to track the delivery of different release versions of a project to different customers or bug fixes made in historical releases.


Glossary

Active Files

Branches

Inactive Files

Local Backup Directory

Local Working Directory

Merging

Reference Directory

Release Directories

Release

VB

Security

Updated Workspace Files

Updated Project Files

Working Revision Comment

Working Revision Number

Workspace


Index

Branching

Comparing and Merging

Conflicts: When Two People Change The Same File

Creating A New Project Without a MAK File

Creating A New SourceWorks Project

Creating Releases

Differences: Merging Each Routine

Differences: Viewing the Different Routines in the File

Directory and Database Structure

File Menu

File Revision History

File View Layout

Get and Put

Getting Started

Good Practice Guidelines

Contents

Glossary

Installation

Loading an Existing VB Project Into SourceWorks

Locking Files

Options Menu

Project Menu

Project Properties

Recovering Historical Files

Recreating Historical Releases

Release History

Support

The Recommended Process

View Menu

Why SourceWorks?

Working with Alternate Releases